Release notes for WebAPI 3.0.22034.1

Bug fixes

  • OAI.ashx did not retrieve values from inherited fields. Fixed in 3.0.22034.1.
  • Getcontent for file types other than images no longer worked. Fixed in 3.0.22019.1.
  • An update to OTMM (OpenText Media Management) caused a change in the OTMM metadata returned by the Axiell WebAPI plugin for OTMM to the WebAPI image server. The plugin was coded to look at the master_content node for previews, which is fine if the ingested master is a “known” type (has a recognizable mime-type extension). However, if a master came from tape, which uses an envelope format with an extension of .mxf, the plugin no longer recognized this format, and was going down the wrong route as a result. Since all assets that are viewable have a preview_content node, this node will now be used instead of the master_content node for the metadata crawl. Fixed in 3.0.22013.1.
  • In a WebAPI getcontent call it was possible to provide the path to some local file in the “value” parameter, even if that path was beyond the image server path, which was not safe. The fix does not allow local files to be included this way if their path is beyond the path configured for the image server. If an attempt is made to include a file from a higher folder anyway, an error is returned: <message>Error retrieving document for content id: relevant_path</message>. Fixed in 3.0.21342.1.
  • OAI performance was still too slow. During creation of the output XML too much data was resolved while it was doing a repcount of fields, the context fields were always filled as well as merged-in fields, even when not requested, and the inheritance functionality also retrieved data in the indexed links, where it was not needed. This has all been fixed in 3.0.21327.1.
  • A Server Side Request Forgery (SSRF) attack is an attack where an attacker is able to supply or modify a URL used by the server to fetch external resources which pose a risk. In the WebAPI this could be achieved by entering a URL to an external resource in the “value” parameter of a getcontent request. This is sometimes intentional and for good but can be used for bad too. A new <whiteList> element, to be included in the globalConfiguration or in the imageServerConfiguration of the image server adlibweb.xml, should now be used to limit allowed external sources to those listed underneath that element in repeatable <url> nodes. A whiteList node in the imageServerConfiguration node overrides a whiteList node configured in the globalConfiguration node. For backwards compatibility, when no whiteList items have been specified in the configuration yet, all requested URLs are still allowed. Fixed in 3.0.21309.1.
  • A WebAPI getcontent request to scale the retrieved image accepted arbitrary dimensions as parameters which allowed an attacker to set the width and height to large values. This could then result in a denial-of-service (DoS) attack since the server would run out of memory and processing power when trying to render the requested large image and possibly lead to the server crashing. This risk can be addressed by setting a maxHeight and maxWidth in the adlibweb.xml. If these options have not been set in the adlibweb.xml, the WebAPI will now assume maximum values of 1000 pixels for both. Fixed in 3.0.21307.1.
  • The WebAPI didn't find a database alias that the older wwwopac version could find indeed. Fixed in 3.0.21322.1.
  • The WebAPI threw an error on the existence of a linked integer field. Fixed in 3.0.21322.1: linked integer fields are allowed (again).
  • When the WebAPI command=insertrecord was used to create a record with a link to another record, an error occured: "No mapping exists from object type Adlib.String.FormattedString to a known managed provider native type". Fixed in 3.0.21319.1.
  • OAI returned same hits for every resumptionToken, so they were of no use. Fixed in 3.0.21307.1.
  • The response time was missing again in the diagnostics section. Fixed in 3.0.21300.1.
  • The WebAPI was slow (or even timed out) when searching on modification date and priref. Fixed in version 3.0.21299.1.
  • OAI jsonv1 type output was missing data about deleted records and resumption tokens. Fixed in 3.0.21277.1. For enumerative fields a difference remains between the pre-3.0.21277.a version of jsonv1 and the new version of jsonv1: spans are missing for this field type, element “lang” is now “@lang” and element “text” is now “#text”: this will not be fixed.
  • Adding an AND NOT operator to the query specified in the OAI <SearchSatement> setting in adlibweb.xml ignored From Until and gave wrong output. Fixed in 3.0.21274.1.
  • Context fields did not show in the WebAPI output, if the source fields were multilingual. Fixed in 3.0.21253.1.
  • In version 3.0.21246.1 the GetContent command no longer worked. Fixed in 3.0.21249.1
  • The sitemap API (sitemapper.ashx) returned empty <sitemapindex/> XML. Fixed in 3.0.21210.1.
  • When a linked record couldn't be found, a DatabaseRecordNotFoundException was thrown which would break the output of WebAPI/OAI requests. Now, the error will be gracefully ignored and just output all fields except the missing one. The error will be logged in the log file when the configuration has debugging on and a log folder defined. Fixed in 3.0.21203.1.
  • The getmetadata command with output=json, no longer returned adlibJSON XML but adlibXML. Fixed in 3.0.21195.1.
  • Users could still request and see restricted information after logging out. Fixed in 3.0.21189.1.
  • Image orientation was lost (ignored) when the image was resized or transformed. Fixed in 3.0.21188.1.
  • Subsequent getcontent calls for media files were no longer working when folder mappings were used, because those calls tried to append a sub folder name to the path of the previously downloaded item, which resulted in invalid paths. Fixed in 3.0.21158.1.
  • Search queries including enumerative fields failed. Fixed in 3.0.21136.1.
  • WebAPI OAI queries on dates with from and until parameters showed slow (up to unresponsive) performance and inconsistent results. Fixed in 3.0.21109.1.
  • The seed parameter for the random command no longer worked. Fixed in 3.0.21096.1.
  • A WebAPI error occurred when retrieving a record in which a filled-in linked field had the Link only first occurrence option disabled. Fixed in 3.0.21082.1.

New functionality

Searching linked fields on a merged-in field, using hierarchical operators

Say you'd like to do a search for objects or containers within a certain location (so you'd want to search on a location and the locations underneath it), using the location's barcode as the search key instead of the location name (where location records are hierarchically linked on name, so the barcode field is a merged-in field), then from WebAPI version 3.0.22025.1 you can. Three new search operators are now available: broader for a search on all broader terms, narrower for a search on all narrower terms and generic for a search on all narrower terms including the search key itself. These operators can be used for linked fields where the linked database has the hierarchical internal link defined (bt/nt) as well as for local indexed fields (other than the term indexed field for the hierarchical internal link in the current database). Two examples of both situations:

wwwopac.ashx?database=collect&search=current_location.barcode generic DIU.V106
wwwopac.ashx?database=package&search=barcode broader DIU.V712

XML payload processing support

The Axiell WebAPI 3.0.21344.1 and higher support the processing of XML payloads to extract their data to write or update Axiell database records using an adapl.
Imagine for example some media ingest software which generates metadata about the result of an ingest action, in the form of a snippet of raw XML or JSON, with the purpose of having some or all of the information in such a file processed in certain Axiell database records, maybe in the media records that were just created or in object records linking to those media records or maybe in some new event records.
The Axiell WebAPI is now capable of requesting such processing with the load command and the payload argument. The processing of the XML file itself however, must be done via a custom adapl. A new <payloadConfiguration> section in the WebAPI adlibweb.xml configuration file specifies the Axiell database name and (location of) the adapl to use, tying it all together. For example (include the section underneath the <webConfiguration> node):

<payloadConfiguration name="my_payload_type1" type="XML">
    <database>collect</database>
    <adapl>C:\Data\Axiell\model452\adapls\myadapl</adapl>
</payloadConfiguration>
  • name is the identifier of this payload configuration and it's this identifier that must be passed as the payload argument in the WebAPI request
  • type is the type of the expected payload data (XML or JSON)
  • database is the name of the database to run this payload for, e.g. collect or document
  • adapl is the name of the custom adapl that should run and parse the payload

So a raw XML or JSON file posted with a wwwopac.ashx?command=load&payload=my_payload_type1 request in this example would process the posted payload file using a custom adapl for a specific database, as set in the adlibweb.xml.
Remember to set <debug>true</debug> here as well if you'd like errorm messages from the adapl to end up in the WebAPI response.

When a WebAPI load request for an available payload is executed, in memory a new blank record is created for the specified database and the adapl is run for that record (which can be saved or not by the adapl), so besides generating errorm messages you can use the adapl to assign data from XML nodes to field tags in the record as you would normally assign values to field tags in e.g. a before-storage adapl. You can also (regardless of what you do with the new record in memory) use the ADAPL FACS functionality to read, update or create records in FACS databases that you specify using regular FACS definitions in the adapl. Click here to read more about programming such an adapl.

JSON output supported by OAI.ashx from version 3.0.21252.1

From WebAPI version 3.0.21252.1, oai.ashx produces JSON (implicitly of the more compact type) if the new setting: <output>json</output> has been configured in the <globalConfiguration> section in the adlibweb.xml configuration file. If you do not configure this option, the OAI result will be grouped XML. The output=xml or output=json query arguments (as supported for wwwopac.ashx) cannot be used for oai.ashx. This OAI functionality is not hindered or influenced by the XML type setting for wwwopac.ashx and vice versa the JSON format or XML type settings for wwwopac.ashx are not hindered by the JSON option for OAI, but if no <jsonFormat> has been specified for wwwopac.ashx then the <output>json</output> setting will cause wwwopac.ashx and oai.ashx (the latter from version 3.0.21273.1) to spit out JSON of the jsonv1 type unless (for wwwopac.ashx) the URL has an output=xml argument: a jsonFormat=standard argument won't work in that case.
For more information about the referenced wwwopac.ashx settings, see the JSON output topic.

Adapl errorm messages optionally logged in WebAPI XML output

if the adaplEnabled variable has been set to True in adlibweb.xml (to specify that when you write or update a record with the WebAPI, the adapl set as storage procedure for the relevant database in Axiell Designer must be executed just before actual storage) and debug has been switched on in that configuration file too, then from WebAPI version 3.0.21245.1, any messages generated by errorm statements in the relevant adapl are included in an <errorMessages> section underneath the <diagnostic> node of the WebAPI XML output. Each error message will be returned in its own <message> node, the first generated message on top and any subsequently generated messages further downwards.

A Piction image plugin

From WebAPI version 3.0.21175.1, an image plugin for the Piction DAMS is available: Axiell.Piction.Plugin.dll. As all other plugins it allows you or your Axiell system (by means of retrieval paths for image fields) to communicate with the DAMS-specific API via the Axiell WebAPI. Please see the full topic for more information.

OAI harvesting and site mapping functionality now standard part of the WebAPI package

OAI and site mapping functionality, through the oai.ashx and sitemapper.ashx api's are now standard part of the WebAPI package. Added in 3.0.21154.1 and 3.0.21210.1 respectively.

Additional field properties isMultiLingual and isInherited in output of the getmetadata function

For secondary or third party software using the WebAPI to write data it is important to know if a field is multilingual or not, because they can corrupt the data if they write non-multilingual data in a multilingual field. And inherited fields shouldn’t usually be written to because they already get their data for display from a parent record dynamically. Therefore two new properties of fields are now included in the output of the getmetadata command: isMultiLingual and isInherited. Added in 3.0.20198.1.

Reporting deleted records in an OAI result set as such

The resulting XML from an OAI search query normally doesn’t report on records missing from the result set if they were deleted in some way earlier. The new version of the WebAPI does allow this type of reporting though, so that it is clear to the harvester why those records are missing. A requirement is that journalling has been enabled for the relevant database (a setting in the .inf): this setting makes sure that record changes and deletions are registered in the database. If journalling is enabled, then from that point on, deleted records will be registered in the database, but they won’t be reported in an OAI result set automatically. To enable the reporting of deleted records you must add a <reportDeletedRecords>true</reportDeletedRecords> node to either the globalConfiguration section or in each of the OAI_SET sections in adlibweb.xml. The per set setting will override the global setting if the relevant set is addressed, so globally you can set it to false whilst setting it to true for a specific OAI_SET. Use the global setting to set it for all OAI_SET configs implicitly. (Note that an Identify request only looks at the global setting and results in a <deletedRecord>No</deletedRecord> node (journalling not switched on or <reportDeletedRecords>false</reportDeletedRecords> is set in the adlibweb.xml) or <deletedRecord>Persistent</deletedRecord> node (journalling is switched on and <reportDeletedRecords>true</reportDeletedRecords> is set in the adlibweb.xml) in the Identify result.) If <reportDeletedRecords>false</reportDeletedRecords> is missing from the configuration, the behaviour defaults to “false”, so deleted records won’t be reported then. If journalling has been switched on and <reportDeletedRecords>true</reportDeletedRecords> has been set, a GetRecord and ListRecords call will include each deleted record in the result set as follows (where collect:12 will be substituted by the relevant database name and record priref and the date by the actual date of deletion):

<record>
<header status="deleted">
<identifier>collect:12</identifier>
<datestamp>2021-06-10T07:56:04Z</datestamp>
</header>
</record>

Functionality added in 3.0.21154.1.

Improvement of the configurability of renditions for the Open Text plugin for the WebAPI image server

The adlibweb.xml configuration for this image plugin now has a section in which to specify alternative renditions for specific content types. The list of Renditions can hold types Application, Video, Audio which relate to the type of content returned by OTMM. For PDFs the type is Application (from mimetype application/pdf). When no rendition exception is defined, the default rendition (as specified in the Rendition node directly underneath ImagePlugin) is still used as a fallback option. An example configuration looks like this:

  <imageServerConfiguration name="aispreviews">
    <defaultImage></defaultImage>
    <servertype>FileSystem</servertype>
    <imageOverlayFile>C:\Axiell\AIS IMAGEAPI\Image0032ShadowBG.png</imageOverlayFile>
    <imageOverlayBlend>65</imageOverlayBlend>
    <imageOverlayPosition>4</imageOverlayPosition>
    <imageOverlayPercentage>30</imageOverlayPercentage>
    <path></path>
    <cachePath>C:\Axiell\imageCache</cachePath>
    <ImagePlugin type="Adlib.OpenText.Imaging.Plugin.OpenTextImagePlugin, OpenTextImagePlugin">
      <BaseUrl>http://ourserver.edu/otmmapi/v4</BaseUrl>
      <UserName>axiellservice</UserName>
      <Password>0p3jk89d7t</Password>
      <Rendition>preview</Rendition>
      <Renditions>
        <Rendition Type="Application">thumbnail</Rendition>
      </Renditions>
    </ImagePlugin>
    <ignoreScaleVideo>true</ignoreScaleVideo>
  </imageServerConfiguration>

So here the default rendition is preview and the exception for Application type content is thumbnail.
Functionality added in version 3.0.21127.1.